package com.liusy.serachengine.demo;

import org.w3c.dom.Document;

public interface Search {
	
	/**
	 * 指标 - 提供了一个枚举，该枚举可以表示要返回的需要的搜索结果数。有效的值包括： 
	 * 请求大量结果（通常 10 个结果） ;
	 */
	public final static int LARGE_RESULTSET = 10;
	
	/**
	 * 请求少量结果（通常 4 个结果） 
	 */
	public final static int SMALL_RESULTSET = 4;
	
	/**
	 * @param indicator
	 *            调用此方法以选择被此特定搜索器返回的结果数。
	 *            请注意，这不是一个标量。它是表示少量结果或大量结果的枚举。将来可能会改进此方法以支持中型的以及超大型结果集。
	 */
	public void setResultSetSize(int indicator);
	 
	/**
	 * 此方法返回了当前结果集大小，值由前一个方法建立。
	 * @return 当前结果集大小。
	 */
	public int getResultSetSize();
	 
	/**
	 *  成功完成搜索时，搜索器对象继续收集搜索结果，这描述了特定搜索的结果。
	 *  此方法用于重设清除所有结果的搜索器。在执行新的搜索之前将含蓄地调用此方法。 
	 */
	public void clearResults(); 
	 
	/**
	 * 调用此方法以开始新的搜索。
	 * query 参数提供了搜索词语。完成时，对象被相应的一组结果填充，以及注册的搜索完成处理程序被调用。 
	 * @param query - 提供了用于执行搜索的查询项
	 * @return {@link Result}
	 */
	public Result execute(String query); 
	
	/**
	 * 取消搜索。
	 */
	public void cancel();

	/**
	 * 此方法用于注册对象和方法以通知搜索完成。应用程序可以通过使用 opt_arguments（之后将被传送到特定的方法）随意传入环境参数。
	 * 
	 * @param object
	 *            - 提供了一个应用程序级别对象，此对象定义了将在其中调用指定方法的环境。
	 * @param method
	 *            - 提供了要调用的方法。例如，如果此方法作为 .setSearchCompleteCallback(foo,
	 *            MyObject.prototype.mySearchCompleteHandler)
	 *            被调用，则当在此搜索器上的搜索完成时，将调用
	 *            foo.mySearchCompleteHandler(opt_arguments?)。
	 * @param opt_arguments
	 */
	public void setSearchCompleteCallback(Object object, String method, Object[] opt_arguments); 
	 
	/**
	 * 此方法用于设置用户定义的标签，当该搜索器被添加到搜索控件时应当使用此标签。
	 * 通过调用此功能，指定的用户定义的标签将代替标准的内置标签在结果节头或标签中被使用。
	 * 预期用途与限制搜索的网站一起配合使用，应用程序将显示它们已通过更改标准标签在限制中编程，这在该限制搜索网站上是合适的也是预期的。
	 * 
	 * @param label
	 *            标签 - 提供了用户定义的标签，可替换在结果节头中的“Web”、“Blog”等等
	 */
	public void setUserDefinedLabel(String label); 
	 
	/**
	 * 此方法用于设置用户定义的类后缀，该类后缀用于搜索结果部分以及用于通过在搜索控件中的该搜索器所产生的搜索结果集合。
	 * 使用此方法的目的在于使应用程序为结果和一组特定搜索结果的标题设置唯一的样式。 假设用 "siteSearch" 这个值调用此方法，则一类
	 * gsc-resultsRoot-siteSearch 将应用于 DIV 元素，这样隐藏与此搜索器相关联的标题和结果。 请注意，这是除了常规的
	 * gsc-resultsRoot 类之外的类。
	 * 
	 * @param classSuffix
	 *            - 提供了用户定义的类后缀，该类后缀会附加到 gsc-resultsRoot-。该类被添加到 DIV
	 *            元素，这将隐藏与此搜索器相关联的标题和结果。
	 */
	public void setUserDefinedClassSuffix(String classSuffix);
	 
	/**
	 * 调用此方法以设置用于嵌入搜索结果中的链接的链接目标。默认值为 g.search.Search.LINK_TARGET_BLANK，该值指定了链接将在新的浏览器窗口中打开。将搜索器添加到搜索控件时，搜索控件将通过使用该搜索控件的当前链接目标设置来隐式调用此方法。这意味着如果您的应用程序需要搜索器来操作不同于搜索控件建立的链接目标设置，则需要在将搜索器添加到该搜索控件之后调用此方法。 
	 * @param linkTarget - 提供了应在其中打开链接的目标框架，有效值包括： 
	 *        a.search.Search.LINK_TARGET_BLANK - 链接会在新的窗口中打开，例如 <A href=... target=_blank ...> 
	 *        a.search.Search.LINK_TARGET_SELF - 链接会在同一窗口和框架中打开，例如 <A href=...target=_self ...> 
	 *        a.search.Search.LINK_TARGET_TOP - 链接会在最顶端的框架中打开，例如 <A href=...target=_top ...> 
	 *        a.search.Search.LINK_TARGET_PARENT - 链接会在最顶端的框架中打开，或者替换当前的框架，例如 <A href=... target=_parent ...> 
	 *        anything-else - 链接将在指定的框架或窗口中打开，例如 A href=... target=anything-else ...> 
	 */
	public void setLinkTarget(String linkTarget);

	/**
	 * 有时您的应用程序不使用此搜索控件，而仅使用来自搜索结果的一小组属性，您可以通过可高度自定义的格式来显示这些属性。
	 * 在此情况下，您的应用程序可进行略微的优化。可以将搜索器编程为不生成 .html 属性，而只在结果中产生有效的原始属性。  
	 */
	public void setNoHtmlGeneration(); 

	/**
	 * 对于某些搜索器类（例如，a.search.LocalSearch()），需要在搜索结果集旁边显示该归属内容。
	 * 当使用搜索控件时，这将“免费”包括在搜索控件逻辑中。如果要使用原始搜索器，将由您决定计算并呈现正确的归属内容。
	 * 此方法旨在为您提供归属内容节点（不需要归属内容时为空），随后您可以适当地进行显示。 
	 * 只有在搜索之后立即主动显示一组搜索结果时，才要求显示归属内容。以下代码段演示了此 API 的简单使用。 
     * var attribution = a.search.LocalSearch.getAttribution();  
     * if (attribution) 
     * {    
     * var el = document.getElementById("searchwell");    
     * el.appendChild(attribution);  
     * }                  
	 * @return 返回 - 非空：需要归属内容。返回值为 HTML 节点，该节点应被添加到您的页面上靠近当前搜索结果集的某个位置。 
	 *         返回 - 空：不需要归属内容 
	 */
	public Document getAttribution();

	/**
	 * 此方法允许调用程序设置（或清除）一个可选的、附加查询条目，该查询条目会附加到通过此搜索器进行的所有查询。
	 * 通常，应用程序将使用此方法来提供可备选结果，这些备选结果与原始搜索词语相比有一定的变化。 例如，假设基于a.search.WebSearch()
	 * 的搜索器将此函数作为 search.setQueryAddition("filetype:pdf"); 来调用，
	 * 然后执行查询“google”，则会产生以下查询“google filetype:pdf”。 当使用该 API 时，我们强烈建议您使用
	 * .setUserDefinedLabel()，以便可以向您的用户显示他们的查询已被修改。 当使用 .setSiteRestriction()
	 * 时，我们同样建议您使用该常规方法。有关详细信息，请访问我们的示例。
	 * 
	 * @param term
	 *            - 提供了附加到通过此搜索器进行的每个查询的表达式（请注意，无需使用空格）。 当条目的值为 "" 时，将取消该 API
	 *            的效果，并且不会修改查询。
	 */
	public void setQueryAddition(String term); 
	 
	/**
	 * 此方法允许调用程序创建或重新生成指定结果的 .html 属性。
	 * 当调用程序先前已经使用 .setNoHtmlGeneration() 时，或当调用程序从其自身的存储系统重新加载结果对象时，有时需要使用此方法。 
	 * 
	 * @param result
	 * @return 结果 - 提供了一个结果对象。它的 .html 属性将被删除并且将作为该调用的结果重新生成。如果结果不包含 .html 属性，则将创建该属性。 
	 *         返回 - n/a
	 */
	public String createResultHtml(Object result); 
	 
	/**
	 * 完成搜索后，cursor 属性在搜索器选项上可能变为可用。这是可用搜索结果数的以及基本搜索器容量的函数。
	 * 如果使用光标属性，则此方法还使您可以提取另外一组搜索结果。
	 * 应用程序通过使用 page 参数来指定页面。然后，将使用该值为 cursor.pages 数组建立索引，该数组最后将用于计算 &start 网址参数的值。 
	 * 
	 * @param page - 提供了应用程序所需的结果的页码。此值是相对于 .cursor.pages 属性检查的范围，如果页面在范围之外，或者基本搜索器没有 cursor 属性，则不执行操作。 
	 */
	public void gotoPage(long page); 
	
}
